home *** CD-ROM | disk | FTP | other *** search
/ Spidla DivX / DivX.bin / FLAC 1.1.0 / include / FLAC / file_decoder.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-01-01  |  23.2 KB  |  649 lines
  1. /* libFLAC - Free Lossless Audio Codec library
  2.  * Copyright (C) 2000,2001,2002,2003  Josh Coalson
  3.  *
  4.  * This library is free software; you can redistribute it and/or
  5.  * modify it under the terms of the GNU Library General Public
  6.  * License as published by the Free Software Foundation; either
  7.  * version 2 of the License, or (at your option) any later version.
  8.  *
  9.  * This library is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.  * Library General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU Library General Public
  15.  * License along with this library; if not, write to the
  16.  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.  * Boston, MA  02111-1307, USA.
  18.  */
  19.  
  20. #ifndef FLAC__FILE_DECODER_H
  21. #define FLAC__FILE_DECODER_H
  22.  
  23. #include "export.h"
  24. #include "seekable_stream_decoder.h"
  25.  
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29.  
  30.  
  31. /** \file include/FLAC/file_decoder.h
  32.  *
  33.  *  \brief
  34.  *  This module contains the functions which implement the file
  35.  *  decoder.
  36.  *
  37.  *  See the detailed documentation in the
  38.  *  \link flac_file_decoder file decoder \endlink module.
  39.  */
  40.  
  41. /** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
  42.  *  \ingroup flac_decoder
  43.  *
  44.  *  \brief
  45.  *  This module contains the functions which implement the file
  46.  *  decoder.
  47.  *
  48.  * The basic usage of this decoder is as follows:
  49.  * - The program creates an instance of a decoder using
  50.  *   FLAC__file_decoder_new().
  51.  * - The program overrides the default settings and sets callbacks for
  52.  *   writing, error reporting, and metadata reporting using
  53.  *   FLAC__file_decoder_set_*() functions.
  54.  * - The program initializes the instance to validate the settings and
  55.  *   prepare for decoding using FLAC__file_decoder_init().
  56.  * - The program calls the FLAC__file_decoder_process_*() functions
  57.  *   to decode data, which subsequently calls the callbacks.
  58.  * - The program finishes the decoding with FLAC__file_decoder_finish(),
  59.  *   which flushes the input and output and resets the decoder to the
  60.  *   uninitialized state.
  61.  * - The instance may be used again or deleted with
  62.  *   FLAC__file_decoder_delete().
  63.  *
  64.  * The file decoder is a trivial wrapper around the
  65.  * \link flac_seekable_stream_decoder seekable stream decoder \endlink
  66.  * meant to simplfy the process of decoding from a standard file.  The
  67.  * file decoder supplies all but the Write/Metadata/Error callbacks.
  68.  * The user needs only to provide the path to the file and the file
  69.  * decoder handles the rest.
  70.  *
  71.  * Like the seekable stream decoder, seeking is exposed through the
  72.  * FLAC__file_decoder_seek_absolute() method.  At any point after the file
  73.  * decoder has been initialized, the user can call this function to seek to
  74.  * an exact sample within the file.  Subsequently, the first time the write
  75.  * callback is called it will be passed a (possibly partial) block starting
  76.  * at that sample.
  77.  *
  78.  * The file decoder also inherits MD5 signature checking from the seekable
  79.  * stream decoder.  If this is turned on before initialization,
  80.  * FLAC__file_decoder_finish() will report when the decoded MD5 signature
  81.  * does not match the one stored in the STREAMINFO block.  MD5 checking is
  82.  * automatically turned off if there is no signature in the STREAMINFO
  83.  * block or when a seek is attempted.
  84.  *
  85.  * Make sure to read the detailed descriptions of the
  86.  * \link flac_seekable_stream_decoder seekable stream decoder module \endlink
  87.  * and \link flac_stream_decoder stream decoder module \endlink
  88.  * since the file decoder inherits much of its behavior from them.
  89.  *
  90.  * \note
  91.  * The "set" functions may only be called when the decoder is in the
  92.  * state FLAC__FILE_DECODER_UNINITIALIZED, i.e. after
  93.  * FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but
  94.  * before FLAC__file_decoder_init().  If this is the case they will
  95.  * return \c true, otherwise \c false.
  96.  *
  97.  * \note
  98.  * FLAC__file_decoder_finish() resets all settings to the constructor
  99.  * defaults, including the callbacks.
  100.  *
  101.  * \{
  102.  */
  103.  
  104.  
  105. /** State values for a FLAC__FileDecoder
  106.  *
  107.  *  The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
  108.  */
  109. typedef enum {
  110.  
  111.     FLAC__FILE_DECODER_OK = 0,
  112.     /**< The decoder is in the normal OK state. */
  113.  
  114.     FLAC__FILE_DECODER_END_OF_FILE,
  115.     /**< The decoder has reached the end of the file. */
  116.  
  117.     FLAC__FILE_DECODER_ERROR_OPENING_FILE,
  118.     /**< An error occurred opening the input file. */
  119.  
  120.     FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
  121.     /**< An error occurred allocating memory. */
  122.  
  123.     FLAC__FILE_DECODER_SEEK_ERROR,
  124.     /**< An error occurred while seeking. */
  125.  
  126.     FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
  127.     /**< An error occurred in the underlying seekable stream decoder. */
  128.  
  129.     FLAC__FILE_DECODER_ALREADY_INITIALIZED,
  130.     /**< FLAC__file_decoder_init() was called when the decoder was already
  131.      * initialized, usually because FLAC__file_decoder_finish() was not
  132.      * called.
  133.      */
  134.  
  135.     FLAC__FILE_DECODER_INVALID_CALLBACK,
  136.     /**< FLAC__file_decoder_init() was called without all callbacks
  137.      * being set.
  138.      */
  139.  
  140.     FLAC__FILE_DECODER_UNINITIALIZED
  141.     /**< The decoder is in the uninitialized state. */
  142.  
  143. } FLAC__FileDecoderState;
  144.  
  145. /** Maps a FLAC__FileDecoderState to a C string.
  146.  *
  147.  *  Using a FLAC__FileDecoderState as the index to this array
  148.  *  will give the string equivalent.  The contents should not be modified.
  149.  */
  150. extern FLAC_API const char * const FLAC__FileDecoderStateString[];
  151.  
  152.  
  153. /***********************************************************************
  154.  *
  155.  * class FLAC__FileDecoder : public FLAC__StreamDecoder
  156.  *
  157.  ***********************************************************************/
  158.  
  159. struct FLAC__FileDecoderProtected;
  160. struct FLAC__FileDecoderPrivate;
  161. /** The opaque structure definition for the file decoder type.  See the
  162.  *  \link flac_file_decoder file decoder module \endlink for a detailed
  163.  *  description.
  164.  */
  165. typedef struct {
  166.     struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
  167.     struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
  168. } FLAC__FileDecoder;
  169.  
  170. /** Signature for the write callback.
  171.  *  See FLAC__file_decoder_set_write_callback()
  172.  *  and FLAC__SeekableStreamDecoderWriteCallback for more info.
  173.  *
  174.  * \param  decoder  The decoder instance calling the callback.
  175.  * \param  frame    The description of the decoded frame.
  176.  * \param  buffer   An array of pointers to decoded channels of data.
  177.  * \param  client_data  The callee's client data set through
  178.  *                      FLAC__file_decoder_set_client_data().
  179.  * \retval FLAC__StreamDecoderWriteStatus
  180.  *    The callee's return status.
  181.  */
  182. typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
  183.  
  184. /** Signature for the metadata callback.
  185.  *  See FLAC__file_decoder_set_metadata_callback()
  186.  *  and FLAC__SeekableStreamDecoderMetadataCallback for more info.
  187.  *
  188.  * \param  decoder  The decoder instance calling the callback.
  189.  * \param  metadata The decoded metadata block.
  190.  * \param  client_data  The callee's client data set through
  191.  *                      FLAC__file_decoder_set_client_data().
  192.  */
  193. typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
  194.  
  195. /** Signature for the error callback.
  196.  *  See FLAC__file_decoder_set_error_callback()
  197.  *  and FLAC__SeekableStreamDecoderErrorCallback for more info.
  198.  *
  199.  * \param  decoder  The decoder instance calling the callback.
  200.  * \param  status   The error encountered by the decoder.
  201.  * \param  client_data  The callee's client data set through
  202.  *                      FLAC__file_decoder_set_client_data().
  203.  */
  204. typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
  205.  
  206.  
  207. /***********************************************************************
  208.  *
  209.  * Class constructor/destructor
  210.  *
  211.  ***********************************************************************/
  212.  
  213. /** Create a new file decoder instance.  The instance is created with
  214.  *  default settings; see the individual FLAC__file_decoder_set_*()
  215.  *  functions for each setting's default.
  216.  *
  217.  * \retval FLAC__FileDecoder*
  218.  *    \c NULL if there was an error allocating memory, else the new instance.
  219.  */
  220. FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
  221.  
  222. /** Free a decoder instance.  Deletes the object pointed to by \a decoder.
  223.  *
  224.  * \param decoder  A pointer to an existing decoder.
  225.  * \assert
  226.  *    \code decoder != NULL \endcode
  227.  */
  228. FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
  229.  
  230.  
  231. /***********************************************************************
  232.  *
  233.  * Public class method prototypes
  234.  *
  235.  ***********************************************************************/
  236.  
  237. /** Set the "MD5 signature checking" flag.
  238.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  239.  *  FLAC__seekable_stream_decoder_set_md5_checking().
  240.  *
  241.  * \default \c false
  242.  * \param  decoder  A decoder instance to set.
  243.  * \param  value    See above.
  244.  * \assert
  245.  *    \code decoder != NULL \endcode
  246.  * \retval FLAC__bool
  247.  *    \c false if the decoder is already initialized, else \c true.
  248.  */
  249. FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
  250.  
  251. /** Set the input file name to decode.
  252.  *
  253.  * \default \c "-"
  254.  * \param  decoder  A decoder instance to set.
  255.  * \param  value    The input file name, or "-" for \c stdin.
  256.  * \assert
  257.  *    \code decoder != NULL \endcode
  258.  *    \code value != NULL \endcode
  259.  * \retval FLAC__bool
  260.  *    \c false if the decoder is already initialized, or there was a memory
  261.  *    allocation error, else \c true.
  262.  */
  263. FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
  264.  
  265. /** Set the write callback.
  266.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  267.  *  FLAC__seekable_stream_decoder_set_write_callback().
  268.  *
  269.  * \note
  270.  * The callback is mandatory and must be set before initialization.
  271.  *
  272.  * \default \c NULL
  273.  * \param  decoder  A decoder instance to set.
  274.  * \param  value    See above.
  275.  * \assert
  276.  *    \code decoder != NULL \endcode
  277.  *    \code value != NULL \endcode
  278.  * \retval FLAC__bool
  279.  *    \c false if the decoder is already initialized, else \c true.
  280.  */
  281. FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
  282.  
  283. /** Set the metadata callback.
  284.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  285.  *  FLAC__seekable_stream_decoder_set_metadata_callback().
  286.  *
  287.  * \note
  288.  * The callback is mandatory and must be set before initialization.
  289.  *
  290.  * \default \c NULL
  291.  * \param  decoder  A decoder instance to set.
  292.  * \param  value    See above.
  293.  * \assert
  294.  *    \code decoder != NULL \endcode
  295.  *    \code value != NULL \endcode
  296.  * \retval FLAC__bool
  297.  *    \c false if the decoder is already initialized, else \c true.
  298.  */
  299. FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
  300.  
  301. /** Set the error callback.
  302.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  303.  *  FLAC__seekable_stream_decoder_set_error_callback().
  304.  *
  305.  * \note
  306.  * The callback is mandatory and must be set before initialization.
  307.  *
  308.  * \default \c NULL
  309.  * \param  decoder  A decoder instance to set.
  310.  * \param  value    See above.
  311.  * \assert
  312.  *    \code decoder != NULL \endcode
  313.  *    \code value != NULL \endcode
  314.  * \retval FLAC__bool
  315.  *    \c false if the decoder is already initialized, else \c true.
  316.  */
  317. FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
  318.  
  319. /** Set the client data to be passed back to callbacks.
  320.  *  This value will be supplied to callbacks in their \a client_data
  321.  *  argument.
  322.  *
  323.  * \default \c NULL
  324.  * \param  decoder  A decoder instance to set.
  325.  * \param  value    See above.
  326.  * \assert
  327.  *    \code decoder != NULL \endcode
  328.  * \retval FLAC__bool
  329.  *    \c false if the decoder is already initialized, else \c true.
  330.  */
  331. FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
  332.  
  333. /** This is inherited from FLAC__SeekableStreamDecoder; see
  334.  *  FLAC__seekable_stream_decoder_set_metadata_respond().
  335.  *
  336.  * \default By default, only the \c STREAMINFO block is returned via the
  337.  *          metadata callback.
  338.  * \param  decoder  A decoder instance to set.
  339.  * \param  type     See above.
  340.  * \assert
  341.  *    \code decoder != NULL \endcode
  342.  *    \a type is valid
  343.  * \retval FLAC__bool
  344.  *    \c false if the decoder is already initialized, else \c true.
  345.  */
  346. FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
  347.  
  348. /** This is inherited from FLAC__SeekableStreamDecoder; see
  349.  *  FLAC__seekable_stream_decoder_set_metadata_respond_application().
  350.  *
  351.  * \default By default, only the \c STREAMINFO block is returned via the
  352.  *          metadata callback.
  353.  * \param  decoder  A decoder instance to set.
  354.  * \param  id       See above.
  355.  * \assert
  356.  *    \code decoder != NULL \endcode
  357.  *    \code id != NULL \endcode
  358.  * \retval FLAC__bool
  359.  *    \c false if the decoder is already initialized, else \c true.
  360.  */
  361. FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
  362.  
  363. /** This is inherited from FLAC__SeekableStreamDecoder; see
  364.  *  FLAC__seekable_stream_decoder_set_metadata_respond_all().
  365.  *
  366.  * \default By default, only the \c STREAMINFO block is returned via the
  367.  *          metadata callback.
  368.  * \param  decoder  A decoder instance to set.
  369.  * \assert
  370.  *    \code decoder != NULL \endcode
  371.  * \retval FLAC__bool
  372.  *    \c false if the decoder is already initialized, else \c true.
  373.  */
  374. FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
  375.  
  376. /** This is inherited from FLAC__SeekableStreamDecoder; see
  377.  *  FLAC__seekable_stream_decoder_set_metadata_ignore().
  378.  *
  379.  * \default By default, only the \c STREAMINFO block is returned via the
  380.  *          metadata callback.
  381.  * \param  decoder  A decoder instance to set.
  382.  * \param  type     See above.
  383.  * \assert
  384.  *    \code decoder != NULL \endcode
  385.  *    \a type is valid
  386.  * \retval FLAC__bool
  387.  *    \c false if the decoder is already initialized, else \c true.
  388.  */
  389. FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
  390.  
  391. /** This is inherited from FLAC__SeekableStreamDecoder; see
  392.  *  FLAC__seekable_stream_decoder_set_metadata_ignore_application().
  393.  *
  394.  * \default By default, only the \c STREAMINFO block is returned via the
  395.  *          metadata callback.
  396.  * \param  decoder  A decoder instance to set.
  397.  * \param  id       See above.
  398.  * \assert
  399.  *    \code decoder != NULL \endcode
  400.  *    \code id != NULL \endcode
  401.  * \retval FLAC__bool
  402.  *    \c false if the decoder is already initialized, else \c true.
  403.  */
  404. FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
  405.  
  406. /** This is inherited from FLAC__SeekableStreamDecoder; see
  407.  *  FLAC__seekable_stream_decoder_set_metadata_ignore_all().
  408.  *
  409.  * \default By default, only the \c STREAMINFO block is returned via the
  410.  *          metadata callback.
  411.  * \param  decoder  A decoder instance to set.
  412.  * \assert
  413.  *    \code decoder != NULL \endcode
  414.  * \retval FLAC__bool
  415.  *    \c false if the decoder is already initialized, else \c true.
  416.  */
  417. FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
  418.  
  419. /** Get the current decoder state.
  420.  *
  421.  * \param  decoder  A decoder instance to query.
  422.  * \assert
  423.  *    \code decoder != NULL \endcode
  424.  * \retval FLAC__FileDecoderState
  425.  *    The current decoder state.
  426.  */
  427. FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
  428.  
  429. /** Get the state of the underlying seekable stream decoder.
  430.  *  Useful when the file decoder state is
  431.  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
  432.  *
  433.  * \param  decoder  A decoder instance to query.
  434.  * \assert
  435.  *    \code decoder != NULL \endcode
  436.  * \retval FLAC__SeekableStreamDecoderState
  437.  *    The seekable stream decoder state.
  438.  */
  439. FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
  440.  
  441. /** Get the state of the underlying stream decoder.
  442.  *  Useful when the file decoder state is
  443.  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
  444.  *  decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
  445.  *
  446.  * \param  decoder  A decoder instance to query.
  447.  * \assert
  448.  *    \code decoder != NULL \endcode
  449.  * \retval FLAC__StreamDecoderState
  450.  *    The seekable stream decoder state.
  451.  */
  452. FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
  453.  
  454. /** Get the current decoder state as a C string.
  455.  *  This version automatically resolves
  456.  *  \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the
  457.  *  seekable stream decoder's state.
  458.  *
  459.  * \param  decoder  A decoder instance to query.
  460.  * \assert
  461.  *    \code decoder != NULL \endcode
  462.  * \retval const char *
  463.  *    The decoder state as a C string.  Do not modify the contents.
  464.  */
  465. FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
  466.  
  467. /** Get the "MD5 signature checking" flag.
  468.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  469.  *  FLAC__seekable_stream_decoder_get_md5_checking().
  470.  *
  471.  * \param  decoder  A decoder instance to query.
  472.  * \assert
  473.  *    \code decoder != NULL \endcode
  474.  * \retval FLAC__bool
  475.  *    See above.
  476.  */
  477. FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
  478.  
  479. /** This is inherited from FLAC__SeekableStreamDecoder; see
  480.  *  FLAC__seekable_stream_decoder_get_channels().
  481.  *
  482.  * \param  decoder  A decoder instance to query.
  483.  * \assert
  484.  *    \code decoder != NULL \endcode
  485.  * \retval unsigned
  486.  *    See above.
  487.  */
  488. FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
  489.  
  490. /** This is inherited from FLAC__SeekableStreamDecoder; see
  491.  *  FLAC__seekable_stream_decoder_get_channel_assignment().
  492.  *
  493.  * \param  decoder  A decoder instance to query.
  494.  * \assert
  495.  *    \code decoder != NULL \endcode
  496.  * \retval FLAC__ChannelAssignment
  497.  *    See above.
  498.  */
  499. FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
  500.  
  501. /** This is inherited from FLAC__SeekableStreamDecoder; see
  502.  *  FLAC__seekable_stream_decoder_get_bits_per_sample().
  503.  *
  504.  * \param  decoder  A decoder instance to query.
  505.  * \assert
  506.  *    \code decoder != NULL \endcode
  507.  * \retval unsigned
  508.  *    See above.
  509.  */
  510. FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
  511.  
  512. /** This is inherited from FLAC__SeekableStreamDecoder; see
  513.  *  FLAC__seekable_stream_decoder_get_sample_rate().
  514.  *
  515.  * \param  decoder  A decoder instance to query.
  516.  * \assert
  517.  *    \code decoder != NULL \endcode
  518.  * \retval unsigned
  519.  *    See above.
  520.  */
  521. FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
  522.  
  523. /** This is inherited from FLAC__SeekableStreamDecoder; see
  524.  *  FLAC__seekable_stream_decoder_get_blocksize().
  525.  *
  526.  * \param  decoder  A decoder instance to query.
  527.  * \assert
  528.  *    \code decoder != NULL \endcode
  529.  * \retval unsigned
  530.  *    See above.
  531.  */
  532. FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
  533.  
  534. /** This is inherited from FLAC__SeekableStreamDecoder; see
  535.  *  FLAC__seekable_stream_decoder_get_decode_position().
  536.  *
  537.  * \param  decoder   A decoder instance to query.
  538.  * \param  position  Address at which to return the desired position.
  539.  * \assert
  540.  *    \code decoder != NULL \endcode
  541.  *    \code position != NULL \endcode
  542.  * \retval FLAC__bool
  543.  *    \c true if successful, \c false if there was an error from
  544.  *    the 'tell' callback.
  545.  */
  546. FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
  547.  
  548. /** Initialize the decoder instance.
  549.  *  Should be called after FLAC__file_decoder_new() and
  550.  *  FLAC__file_decoder_set_*() but before any of the
  551.  *  FLAC__file_decoder_process_*() functions.  Will set and return
  552.  *  the decoder state, which will be FLAC__FILE_DECODER_OK if
  553.  *  initialization succeeded.
  554.  *
  555.  * \param  decoder  An uninitialized decoder instance.
  556.  * \assert
  557.  *    \code decoder != NULL \endcode
  558.  * \retval FLAC__FileDecoderState
  559.  *    \c FLAC__FILE_DECODER_OK if initialization was successful; see
  560.  *    FLAC__FileDecoderState for the meanings of other return values.
  561.  */
  562. FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
  563.  
  564. /** Finish the decoding process.
  565.  *  Flushes the decoding buffer, releases resources, resets the decoder
  566.  *  settings to their defaults, and returns the decoder state to
  567.  *  FLAC__FILE_DECODER_UNINITIALIZED.
  568.  *
  569.  *  In the event of a prematurely-terminated decode, it is not strictly
  570.  *  necessary to call this immediately before FLAC__file_decoder_delete()
  571.  *  but it is good practice to match every FLAC__file_decoder_init() with
  572.  *  a FLAC__file_decoder_finish().
  573.  *
  574.  * \param  decoder  An uninitialized decoder instance.
  575.  * \assert
  576.  *    \code decoder != NULL \endcode
  577.  * \retval FLAC__bool
  578.  *    \c false if MD5 checking is on AND a STREAMINFO block was available
  579.  *    AND the MD5 signature in the STREAMINFO block was non-zero AND the
  580.  *    signature does not match the one computed by the decoder; else
  581.  *    \c true.
  582.  */
  583. FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
  584.  
  585. /** This is inherited from FLAC__SeekableStreamDecoder; see
  586.  *  FLAC__seekable_stream_decoder_process_single().
  587.  *
  588.  * \param  decoder  A decoder instance.
  589.  * \assert
  590.  *    \code decoder != NULL \endcode
  591.  * \retval FLAC__bool
  592.  *    See above.
  593.  */
  594. FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
  595.  
  596. /** This is inherited from FLAC__SeekableStreamDecoder; see
  597.  *  FLAC__seekable_stream_decoder_process_until_end_of_metadata().
  598.  *
  599.  * \param  decoder  A decoder instance.
  600.  * \assert
  601.  *    \code decoder != NULL \endcode
  602.  * \retval FLAC__bool
  603.  *    See above.
  604.  */
  605. FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
  606.  
  607. /** This is inherited from FLAC__SeekableStreamDecoder; see
  608.  *  FLAC__seekable_stream_decoder_process_until_end_of_stream().
  609.  *
  610.  * \param  decoder  A decoder instance.
  611.  * \assert
  612.  *    \code decoder != NULL \endcode
  613.  * \retval FLAC__bool
  614.  *    See above.
  615.  */
  616. FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
  617.  
  618. /** This is inherited from FLAC__SeekableStreamDecoder; see
  619.  *  FLAC__seekable_stream_decoder_process_remaining_frames().
  620.  *
  621.  * \param  decoder  A decoder instance.
  622.  * \assert
  623.  *    \code decoder != NULL \endcode
  624.  * \retval FLAC__bool
  625.  *    See above.
  626.  */
  627. FLAC_API FLAC__bool FLAC__file_decoder_process_remaining_frames(FLAC__FileDecoder *decoder);
  628.  
  629. /** Flush the input and seek to an absolute sample.
  630.  *  This is inherited from FLAC__SeekableStreamDecoder; see
  631.  *  FLAC__seekable_stream_decoder_seek_absolute().
  632.  *
  633.  * \param  decoder  A decoder instance.
  634.  * \param  sample   The target sample number to seek to.
  635.  * \assert
  636.  *    \code decoder != NULL \endcode
  637.  * \retval FLAC__bool
  638.  *    \c true if successful, else \c false.
  639.  */
  640. FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
  641.  
  642. /* \} */
  643.  
  644. #ifdef __cplusplus
  645. }
  646. #endif
  647.  
  648. #endif
  649.